feat(evm): opt-in short-circuit for future blocks without served-tip - #33

- server.webSocket: buffer and message sizes, ping interval, per-
  connection subscription and in-flight request limits, and the per-
  subscription notification buffer; validated.
- indexer: dedupWindowSize (canonicalChainDepth is accepted and ignored).
- networks[].failover / networkDefaults.failover: onDefaultsExhausted,
  with a validation-report warning when no upstream is tagged
  tier:fallback.
- evm.stripSubscribeFromBlockZero, inherited from networkDefaults.
- Metrics for WebSocket connectivity, dropped subscription
  notifications and the fallback escape; generated TS types.

Co-authored-by: snowkide <[email protected]>
Co-authored-by: João Gomes <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>

ws:// and wss:// endpoints get a persistent client instead of the
"not implemented" stub. It serves regular requests and upstream
subscriptions:

- one read loop owns the connection lifecycle; re-dials wait a jittered
  exponential backoff (1s-30s) that resets only after a connection
  outlives the liveness window; ping/pong plus a read deadline detect
  half-open connections;
- requests fail fast with a retryable error while reconnecting and
  errors are normalised exactly like the HTTP client's;
- subscription handlers are registered before the next frame is read
  and are scoped to the connection that created them; eth_subscribe and
  eth_unsubscribe are only sent on behalf of a subscription owner.

Upstream.IsDown checks the breaker of the policy serving a method, and
the registry exposes the WebSocket and fallback-escape upstream sets.

A response the read loop already claimed reaches its caller even if the
caller's context expired meanwhile, so a subscribe that completed is
never left without an owner; a notification for a subscription no
handler owns triggers eth_unsubscribe, which also retries a cancel that
failed. A panic in a subscription handler or callback is recovered per
frame. jsonRpc.proxyPool is refused for ws/wss upstreams, whose dialer
has no proxy support.

Co-authored-by: snowkide <[email protected]>
Co-authored-by: João Gomes <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>

- enforceHighestBlock also applies to cache hits and keeps the caller's
  use-upstream selector; when the re-fetch misses it still serves the
  highest valid block.
- Cached latest/finalized entries are keyed by the block the tag
  currently resolves to, so each tip advance is a new key.
- Only the observed tx_replay_attack token is treated as already known.

Co-authored-by: shpookas <[email protected]>
Co-authored-by: João Gomes <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>

- Delivered-head floor: a head already delivered on a WebSocket
  subscription, from an upstream eligible to serve the network, floors
  "latest" so HTTP never regresses below it. It is bounded against live
  heads, per project, skipped for use-upstream requests, never lifts
  past servedTip guarantees, and shared across instances in the
  background.
- failover.onDefaultsExhausted: when every routed upstream failed with
  an error retryable toward the network, retry the request once on
  tier:fallback upstreams not yet tried, before the selection policy
  promotes them. Empty results count only for a block that should
  exist; consensus is excluded. The escape honours a use-upstream pin,
  and keeps the routed upstreams' empty answer if every fallback fails.
- Near-tip eth_getBlockByNumber prefers an upstream strictly ahead of
  the others; requests for a specific block try upstreams that have it
  first, preserving score order.
- Non-retryable writes are not multiplexed.

Co-authored-by: shpookas <[email protected]>
Co-authored-by: João Gomes <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>

The indexer sits between event ingresses and egresses:

- ingresses push StreamEvents; newHeads from every source update that
  upstream's poller before dedup, then heads are delivered once and in
  order per network;
- filter subscriptions (logs, newPendingTransactions) are refcounted
  per params key so clients share one upstream subscription per
  upstream, with subscribe and teardown serialised per filter;
- logs are deduplicated by blockHash/transactionHash/logIndex, with the
  upstream's own removed flag tracked per log so add, remove and re-add
  are each delivered once;
- adapters: wsupstream (WebSocket upstream ingress with resubscribe on
  reconnect), wsclient (per-connection egress with bounded per-
  subscription buffers) and nullingress (fixture ingress for tests).

Co-authored-by: snowkide <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>

HTTP and WebSocket share the port and URL paths. Over WebSocket:

- single and batch requests run through the same pipeline as HTTP:
  forward headers, method filters, auth, directives with
  allowClientDirectives, rate limits and server.maxTimeout, with a
  per-connection in-flight limit;
- eth_subscribe/eth_unsubscribe for newHeads, logs and
  newPendingTransactions via the indexer, with connection-scoped
  subscription ids and a per-connection subscription limit;
- a slow reader drops its own oldest newHeads/pending-tx notifications;
  a logs subscription that overflows closes the connection with 1013;
- peers silent for two ping intervals are dropped; on shutdown clients
  are closed with 1001 immediately while in-flight requests finish.

Only a real RFC 6455 handshake bypasses gzip and maxTimeout. The
method-not-allowed response now echoes the request id.

Every message authenticates with the upgrade request's credentials, so
an upgrade no auth strategy accepts is refused with 401; method scoping
and rate limits still apply per message. A valid notification (no id)
runs without a reply, alone or in a batch. A request that panics gets
an error carrying its own id, and errors raised before network
resolution use the URL's architecture for their wire code.

Co-authored-by: snowkide <[email protected]>
Co-authored-by: shpookas <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Clients receive each head from whichever WebSocket upstream delivers it
first, eligible to the selection policy or not. Feeding the floor only
from eligible upstreams let HTTP "latest" sit a block behind a head a
subscriber had just received whenever the fastest upstream was excluded
— which a lag-based policy does routinely. Any known source whose poller
accepted the head now feeds it; the floor stays bounded against live
heads.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

On fast chains the upstream that answered "latest" one block behind is
often the one whose own feed just delivered the tip, and so the only
upstream that already has it. Excluding it made the re-fetch return
null from every other upstream and fail open to the stale block. A
corrupted tip is still caught: every upstream returns null for it and
pickHighestBlock keeps the served block.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

gosec G404 flags math/rand in the reconnect backoff. The jitter only
spreads redials; annotate it like the repo's other jitter uses.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

The hedge keeper kept an ErrUpstreamsExhausted whose causes were all
missing-data, on the premise that no sibling leg could do better. A
sibling may be on an upstream this leg never tried, e.g. a leg the
fallback escape sent to a slow fallback while another leg re-swept the
primaries, so the fast miss cancelled the leg about to succeed. Such a
result now keeps the race going; if every leg ends that way the hedge
still returns the last one to the retry layer.

Co-authored-by: Vitas Spokas <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>

newHeads is subscribed on every WebSocket upstream and each head goes
out from whichever source announces it first. With failover on, a
fallback-tier upstream whose WebSocket is faster told clients about a
block no primary had yet; their follow-up reads then missed on the
primaries, or escaped to the fallback while the primaries were healthy.

A fallback's head now reaches clients, and feeds the delivered-head
floor, only while no upstream outside that tier which the selection
policy routes to has a live newHeads subscription of its own. "Down"
is the policy's verdict, as for reads, so custom policies that keep
fallbacks in the ordered list behave the same. A network whose only
WebSocket upstreams are fallbacks, or whose primaries' subscriptions
are dead, keeps receiving fallback heads. A held-back head still
updates that fallback's state poller.

NetworkHandle.SuggestLatestBlock now reports whether the head may be
delivered; the indexer drops it before dedup otherwise.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

logs and newPendingTransactions picked their upstreams once, when the
first client subscribed: on every primary whose eth_subscribe breaker
was closed, on the fallbacks only if every primary rejected the
subscribe. Nothing revisited that for the filter's lifetime, so a
filter went silent when its primaries dropped it, stayed on the
fallbacks after the primaries recovered, and never reached a primary
whose first subscribe failed.

A filter now belongs on every primary the selection policy routes to,
and on the fallback tier while none of those has it live; the indexer
rechecks this on every head, adding and removing the filter as that
changes. The fallbacks hand a filter back only once a primary has it
live, so there is no gap. An upstream whose subscribe fails keeps the
filter and retries it in the background, like its other subscriptions.

Only heads a tip tracker has accepted reach subscribers: a major jump is
verified before it is delivered, and a source with no tracker is
withheld, so an unverified head can't advance the indexer's dedup
marker. The upstream eth_unsubscribe outlives a caller that already
gave up but keeps a live caller deadline.

The indexer and the subscription manager key a network by project and
network, so two projects that define the same network keep their own
upstreams. A filter subscribe is bounded by the attempt timeout, since
callers hold locks across it and a dropped reply on a busy connection
would otherwise never time out.

Co-Authored-By: Claude Opus 5.5 <[email protected]>